# 插件

pmim 插件系统 (`pmim-plugin`).

## 1 概述

插件用来扩展 pmim 的功能, 给用户提供很大的灵活度和便利.
每个插件可相对独立的安装, 用户可以方便的安装, 启用, 管理插件.

目前插件可用来增加 pmim 的双拼方案, 键盘布局, 界面皮肤等.

### 1.1 插件路径

- **`内置插件`**

  默认路径: `server/plugin/`

  pmim 默认安装自带的几个插件. pmim 自身的一部分功能也以插件的形式实现.

- **`用户安装插件`**

  默认路径: `~/.config/pmim/plugin/`

  用户自己安装的插件.

### 1.2 插件 id

用于管理和标识插件.

插件的 `目录名称` 为其 `插件 id`.

比如 `~/.config/pmim/plugin/pmim-ai/` 这个插件, 其插件 id 为 `pmim-ai`.

## 2 插件目录的文件结构

比如:

```
+ ~/.config/pmim/plugin/pmim-ai/
  - pmimp.json
  - README.md
  - LICENSE
  + static/
```

- `pmim-ai/`: 插件根目录, 名称为 `插件 id`.

- `pmimp.json`: 插件描述文件.

- `README.md` (可选): 插件说明文件.

- `LICENSE` (可选): 插件使用的许可协议.

- `static/` (目录, 可选): 插件的静态资源文件.

  可通过 pmim-server `/plugin/插件id/文件` 的 URL 访问.

### 2.1 插件描述文件

位于插件目录 (根目录), 文件名 `pmimp.json`, 比如:
`~/.config/pmim/plugin/pmim-ai/pmimp.json`

文件格式如下 (注释只是为了方便解释, 实际文件 (`json` 格式) 中不存在注释):

```jsonc
{
  "pmim_version": "0.1.0",
  "插件信息": { // 举栗
    "名称": "双拼方案: 自然码",
    "描述": "胖喵拼音内置双拼方案 (2p_zirjma)",
    "版本": "0.1.0",
    "URL": "https://github.com/fm-elpac/pmim-ibus"
  },

  "默认启用": 1
  // 各种类型的插件扩展的部分
}
```

未注明 `可选` 的, 都是必需的值.

- `pmim_version`: 固定值, 必须为 `0.1.0`.

  用于未来的向后兼容检测和处理.

- `插件信息.名称`: 插件的显示名称.

- `插件信息.描述` (可选): 插件的描述.

- `插件信息.版本`: 插件的版本号, 强烈建议使用 **语义化版本 2.0.0**
  <https://semver.org/lang/zh-CN/>

- `插件信息.URL`: 插件项目页面的网址.

- `默认启用` (可选): 插件是否默认启用.

  - `0` 默认不启用, 需要用户在设置中手动启用.

  - `1` 默认启用. 仅对 **内置插件** 有效. 用户自己安装的插件都需要手动启用.

## 3 插件类型

TODO

### 3.1 双拼方案插件

`pmimp.json` 的扩展部分 (比如):

```jsonc
{
  "双拼方案": "双拼.json"
}
```

- `双拼方案`: 指定双拼方案数据文件 (`json`) 的路径 (相对 `static/` 目录).

### 3.2 键盘布局插件

`pmimp.json` 的扩展部分 (比如):

```jsonc
{
  "键盘布局": "布局.json"
}
```

- `键盘布局`: 指定键盘布局数据文件 (`json`) 的路径 (相对 `static/` 目录).

### 3.3 皮肤插件

`pmimp.json` 的扩展部分 (比如):

```jsonc
{
  "皮肤": {
    "入口": "main.js",
    "名称": "pmim-uis-nc",
    "能力": ["im0", "im1", "im2", "conf"]
  }
}
```

- `皮肤.入口`: 代码入口文件 (`js`) 的路径 (相对 `static/` 目录).

- `皮肤.名称`: 对应 Web Components 名称的一部分.

- `皮肤.能力`: 指定皮肤插件的能力.

  - `im0`: PC 固定工具条窗口界面.

  - `im1`: PC 候选框窗口界面.

  - `im2`: 手机软键盘界面.

  - `conf`: 自定义皮肤配置界面.

---

Web Components 组件名称:

- `名称-im0`: PC 固定工具条窗口界面.

- `名称-im1`: PC 候选框窗口界面.

- `名称-im2`: 手机软键盘界面.

- `名称-conf`: 自定义皮肤配置界面.

### 3.4 服务插件

`pmimp.json` 的扩展部分 (比如):

```jsonc
{
  "服务": {
    "入口": "main.js"
  }
}
```

- `服务.入口`: 指定在 Web Worker 中执行的代码的入口文件 (相对插件根目录).

TODO

服务插件的接口 (pmim-server): `/pmims_api/plugin/插件id/接口` (GET/POST)

TODO
